API Gateway Frontend: Federazione GraphQL e Schema Stitching

Nel mondo dello sviluppo di applicazioni web moderne, la gestione dei dati provenienti da più fonti può rappresentare una sfida significativa. Man mano che le applicazioni crescono in complessità e adottano architetture a microservizi, la necessità di un modo unificato ed efficiente per accedere ai dati diventa fondamentale. Un API Gateway Frontend funge da punto di ingresso centrale per le applicazioni client, aggregando i dati da vari servizi di backend e fornendo un'esperienza ottimizzata sia per gli sviluppatori che per gli utenti finali. Questo articolo del blog esplora due potenti tecniche per costruire un API Gateway Frontend: la Federazione GraphQL e lo Schema Stitching.

Cos'è un API Gateway Frontend?

Un API Gateway Frontend è un pattern architetturale in cui un server dedicato agisce come intermediario tra i client frontend (ad es. browser web, app mobili) e più servizi di backend. Semplifica il recupero dei dati:

• Aggregazione dei dati: Combinare dati da più fonti in un'unica risposta.
• Trasformazione dei dati: Adattare i formati dei dati per soddisfare le esigenze del frontend.
• Astrazione della complessità: Nascondere le complessità dei servizi di backend al client.
• Applicazione della sicurezza: Implementare policy di autenticazione e autorizzazione.
• Ottimizzazione delle prestazioni: Mettere in cache i dati ad accesso frequente e ridurre le richieste di rete.

In sostanza, implementa il pattern Backend for Frontend (BFF) su larga scala e consente ai team di frontend di avere un maggiore controllo sulle API che consumano. Nelle organizzazioni più grandi, avere il frontend che gestisce e cura le proprie API può portare a una consegna più rapida e a una ridotta dipendenza dai team di backend.

Perché usare GraphQL per un API Gateway Frontend?

GraphQL è un linguaggio di interrogazione per API e un runtime per soddisfare tali interrogazioni con i dati esistenti. Offre diversi vantaggi rispetto alle tradizionali API REST, rendendolo particolarmente adatto per la costruzione di API Gateway Frontend:

• Recupero dati efficiente: I client richiedono solo i dati di cui hanno bisogno, riducendo l'over-fetching e migliorando le prestazioni.
• Tipizzazione forte: Gli schemi GraphQL definiscono la struttura dei dati, consentendo strumenti e validazione migliori.
• Introspezione: I client possono scoprire i dati e le operazioni disponibili attraverso l'introspezione dello schema.
• Funzionalità in tempo reale: Le sottoscrizioni GraphQL consentono aggiornamenti dei dati in tempo reale.

Sfruttando GraphQL, un API Gateway Frontend può fornire un'interfaccia flessibile, efficiente e intuitiva per gli sviluppatori per accedere ai dati da più servizi di backend. Ciò contrasta nettamente con gli approcci tradizionali che utilizzano endpoint REST multipli, ognuno dei quali deve essere interrogato individualmente e spesso restituisce più dati del necessario.

Federazione GraphQL: Un Approccio Distribuito

Cos'è la Federazione GraphQL?

La Federazione GraphQL è una tecnica potente per costruire un'API GraphQL distribuita componendo più servizi GraphQL (chiamati "sottografi") in un unico schema unificato. Ogni sottografo è responsabile di un dominio o di una fonte di dati specifica, e il gateway di federazione orchestra le query attraverso questi sottografi.

Il concetto centrale ruota attorno a un supergrafo, uno schema GraphQL unico e unificato che rappresenta l'intera API. Questo supergrafo viene costruito componendo schemi GraphQL più piccoli, chiamati sottografi, ognuno dei quali rappresenta un microservizio o una fonte di dati specifica. Il gateway di federazione è responsabile dell'instradamento delle query GraphQL in entrata verso i sottografi appropriati e della combinazione dei risultati in un'unica risposta.

Come Funziona la Federazione GraphQL

1. Definizione del Sottografo: Ogni microservizio espone un'API GraphQL (un sottografo) che definisce i propri dati e operazioni. Questi schemi includono direttive che indicano al gateway di federazione come risolvere tipi e campi. Le direttive chiave includono `@key`, `@external` e `@requires`.
2. Composizione del Supergrafo: Il gateway di federazione (ad es. Apollo Gateway) recupera gli schemi da ogni sottografo e li compone in un unico schema unificato (il supergrafo). Questo processo comporta la risoluzione dei conflitti di tipi e campi e la creazione di relazioni tra tipi attraverso diversi sottografi.
3. Pianificazione ed Esecuzione della Query: Quando un client invia una query GraphQL al gateway, il gateway analizza la query e determina quali sottografi devono essere interrogati per soddisfare la richiesta. Quindi distribuisce la query ai sottografi appropriati, raccoglie i risultati e li combina in un'unica risposta, che viene restituita al client.

Esempio: Piattaforma E-commerce con Federazione GraphQL

Consideriamo una piattaforma e-commerce con microservizi separati per prodotti, clienti e ordini.

• Sottografo Prodotti: Gestisce le informazioni sui prodotti (nome, descrizione, prezzo, ecc.).
• Sottografo Clienti: Gestisce i dati dei clienti (nome, indirizzo, email, ecc.).
• Sottografo Ordini: Gestisce le informazioni sugli ordini (ID ordine, ID cliente, ID prodotti, importo totale, ecc.).

Ogni sottografo espone un'API GraphQL, e il gateway di federazione compone queste API in un unico supergrafo. Un client può quindi interrogare il supergrafo per recuperare informazioni su prodotti, clienti e ordini in un'unica richiesta.

Ad esempio, una query per recuperare il nome di un cliente e la cronologia dei suoi ordini potrebbe assomigliare a questa:

query GetCustomerAndOrders($customerId: ID!) {
  customer(id: $customerId) {
    id
    name
    orders {
      id
      orderDate
      totalAmount
    }
  }
}

Il gateway di federazione instraderebbe questa query ai sottografi Clienti e Ordini, recupererebbe i dati necessari e li combinerebbe in un'unica risposta.

Vantaggi della Federazione GraphQL

• Accesso ai dati semplificato: I client interagiscono con un singolo endpoint GraphQL, indipendentemente dalle fonti di dati sottostanti.
• Prestazioni migliorate: Il recupero dei dati è ottimizzato recuperando solo i dati necessari da ogni sottografo.
• Scalabilità aumentata: Ogni sottografo può essere scalato indipendentemente, consentendo un migliore utilizzo delle risorse.
• Sviluppo decentralizzato: I team possono sviluppare e distribuire sottografi in modo indipendente, promuovendo agilità e innovazione.
• Governance dello schema: Il gateway di federazione garantisce la coerenza e la compatibilità dello schema tra i sottografi.

Strumenti per la Federazione GraphQL

• Apollo Federation: Una popolare implementazione open-source della Federazione GraphQL, che fornisce un gateway, un registro degli schemi e strumenti per costruire e gestire API GraphQL federate. Apollo Federation è nota per la sua scalabilità e la robusta gestione degli errori.
• GraphQL Hive: Questo strumento offre un registro degli schemi e governance per i servizi federati GraphQL, fornendo funzionalità come il rilevamento delle modifiche, l'analisi dell'utilizzo e i controlli dello schema. Migliora la visibilità e il controllo sul supergrafo.

Schema Stitching: Un Approccio Alternativo

Cos'è lo Schema Stitching?

Lo Schema Stitching è un'altra tecnica per combinare più schemi GraphQL in un unico schema unificato. A differenza della Federazione, lo Schema Stitching comporta tipicamente un processo più manuale per definire come sono collegati i tipi e i campi di schemi diversi. Sebbene la Federazione sia considerata una soluzione più moderna e robusta, lo Schema Stitching può essere un'opzione valida per casi d'uso più semplici o durante la migrazione da API GraphQL esistenti.

Come Funziona lo Schema Stitching

1. Definizione dello Schema: Ogni microservizio espone un'API GraphQL con il proprio schema.
2. Logica di Stitching: Un livello di stitching (spesso implementato usando librerie come GraphQL Tools) definisce come i tipi e i campi di schemi diversi sono collegati. Ciò comporta la scrittura di funzioni resolver che recuperano i dati dai servizi sottostanti e li mappano sullo schema unificato.
3. Schema Unificato: Il livello di stitching combina gli schemi individuali in un unico schema unificato che viene esposto al client.

Esempio: Unire (Stitching) Prodotti e Recensioni

Immaginiamo due servizi GraphQL separati: uno per i prodotti e un altro per le recensioni.

• Servizio Prodotti: Fornisce informazioni sui prodotti (ID, nome, descrizione, prezzo).
• Servizio Recensioni: Fornisce recensioni per i prodotti (ID, ID prodotto, valutazione, commento).

Utilizzando lo Schema Stitching, è possibile creare uno schema unificato che consente ai client di recuperare informazioni sui prodotti e le recensioni in un'unica query.

Si definirebbe una funzione resolver nel livello di stitching che recupera le recensioni per un dato ID prodotto dal Servizio Recensioni e le aggiunge al tipo Prodotto nello schema unificato.

// Example (Conceptual): Stitching logic using GraphQL Tools
const { stitchSchemas } = require('@graphql-tools/stitch');

const productsSchema = ... // Define your products schema
const reviewsSchema = ... // Define your reviews schema

const stitchedSchema = stitchSchemas({
  subschemas: [
    {
      schema: productsSchema,
    },
    {
      schema: reviewsSchema,
      transforms: [
        {
          transformSchema: (schema) => schema,
          transformRequest: (originalRequest) => {
            return originalRequest;
          },
          transformResult: (originalResult) => {
            return originalResult;
          }
        }
      ],
    },
  ],
  typeDefs: `
    extend type Product {
      reviews: [Review]
    }
  `,
  resolvers: {
    Product: {
      reviews: {
        resolve: (product, args, context, info) => {
          // Fetch reviews for the product from the Reviews Service
          return fetchReviewsForProduct(product.id);
        },
      },
    },
  },
});

Questo esempio dimostra il concetto fondamentale dell'unione degli schemi. Si noti la necessità di resolver personalizzati per recuperare il campo `reviews`. Questo overhead aggiuntivo di codifica dei resolver per ogni relazione può rendere il processo di sviluppo più lento rispetto all'uso della Federazione.

Vantaggi dello Schema Stitching

• API Unificata: I client accedono a un singolo endpoint GraphQL, semplificando l'accesso ai dati.
• Adozione incrementale: Lo Schema Stitching può essere implementato in modo incrementale, consentendo di migrare gradualmente a un'API unificata.
• Flessibilità: Lo Schema Stitching offre un maggiore controllo su come vengono combinati gli schemi, consentendo di personalizzare la logica di stitching per soddisfare esigenze specifiche.

Svantaggi dello Schema Stitching

• Configurazione manuale: Lo Schema Stitching richiede una configurazione manuale della logica di stitching, che può essere complessa e richiedere tempo.
• Overhead prestazionale: Le funzioni resolver possono introdurre un overhead prestazionale, specialmente se comportano trasformazioni di dati complesse.
• Scalabilità limitata: Lo Schema Stitching può essere più difficile da scalare rispetto alla Federazione, poiché la logica di stitching è tipicamente centralizzata.
• Proprietà dello schema: Può portare ad ambiguità riguardo alla proprietà dello schema, in particolare se team diversi gestiscono i servizi uniti.

Strumenti per lo Schema Stitching

• GraphQL Tools: Una libreria popolare per costruire e manipolare schemi GraphQL, incluso il supporto per lo Schema Stitching.
• GraphQL Mesh: GraphQL Mesh consente di utilizzare il linguaggio di query GraphQL per accedere a dati da varie fonti come API REST, database e gRPC. Può unire queste API in uno schema GraphQL unificato.

Federazione GraphQL vs. Schema Stitching: Un Confronto

Sia la Federazione GraphQL che lo Schema Stitching offrono modi per combinare più schemi GraphQL in un'unica API, ma differiscono nel loro approccio e nelle loro capacità.

Caratteristica	Federazione GraphQL	Schema Stitching
Approccio	Composizione distribuita e automatizzata	Configurazione centralizzata e manuale
Complessità	Minore complessità per manutenzione e scalabilità	Maggiore complessità a causa della logica manuale dei resolver
Scalabilità	Progettata per sistemi distribuiti su larga scala	Meno scalabile, tipicamente usata per applicazioni più piccole
Governance dello schema	Governance e validazione dello schema integrate	Richiede gestione e coordinamento manuale dello schema
Strumenti	Forte ecosistema di strumenti e librerie (es. Apollo Federation)	Richiede più strumenti e configurazioni personalizzate
Casi d'Uso	Architetture a microservizi, API su larga scala, sviluppo decentralizzato	Applicazioni più piccole, migrazione incrementale, requisiti di personalizzazione specifici

Quando usare la Federazione GraphQL: Scegliere la Federazione quando si ha un'architettura a microservizi complessa, si necessita di scalare l'API e si vuole dare ai team indipendenti la possibilità di gestire i propri sottografi. Semplifica anche la gestione e la governance dello schema.

Quando usare lo Schema Stitching: Considerare lo Schema Stitching quando si ha un'API più semplice, si necessita di maggiore controllo sulla logica di stitching o si sta migrando da API GraphQL esistenti. Tuttavia, essere consapevoli delle potenziali complessità e limitazioni di scalabilità.

Implementazione di Autenticazione e Autorizzazione

Indipendentemente dal fatto che si scelga la Federazione GraphQL o lo Schema Stitching, implementare l'autenticazione e l'autorizzazione è cruciale per proteggere il proprio API Gateway Frontend. Ci sono diversi approcci che si possono adottare:

• Autenticazione a livello di Gateway: L'API Gateway gestisce l'autenticazione e l'autorizzazione prima di instradare le richieste ai servizi di backend. Questo approccio centralizza la logica di sicurezza e semplifica i servizi di backend. Metodi comuni includono la validazione di JWT (JSON Web Token) e OAuth 2.0.
• Autenticazione a livello di Servizio: Ogni servizio di backend gestisce la propria autenticazione e autorizzazione. Questo approccio fornisce un controllo più granulare sulla sicurezza ma può essere più complesso da gestire.
• Approccio Ibrido: Una combinazione di autenticazione a livello di gateway e di servizio. Il gateway gestisce l'autenticazione iniziale e i servizi di backend eseguono controlli di autorizzazione più granulari.

Esempio: Autenticazione JWT con Apollo Federation

Con Apollo Federation, è possibile configurare il gateway per validare i token JWT inclusi negli header della richiesta. Il gateway può quindi passare le informazioni dell'utente estratte dal token ai sottografi, che possono utilizzare queste informazioni per l'autorizzazione.

// Example (Conceptual): Apollo Gateway configuration with JWT validation
const { ApolloGateway } = require('@apollo/gateway');

const gateway = new ApolloGateway({
  serviceList: [
    // ... your subgraph configurations
  ],
  buildService: ({ name, url }) => {
    return new MyCustomService({
      name,  // Name of the subgraph
      url,   // URL of the subgraph
    });
  },
});

class MyCustomService extends RemoteGraphQLDataSource {
  willSendRequest({ request, context }) {
    // Get the user from the context
    const user = context.user;

    // Add the user's ID to the request headers
    if (user) {
      request.http.headers.set('user-id', user.id);
    }
  }
}

In questo esempio, viene creato un servizio personalizzato per modificare le richieste in uscita in modo da includere l'ID utente derivato dal JWT. I servizi a valle possono quindi utilizzare questo ID per i controlli di autorizzazione.

Strategie di Caching per l'Ottimizzazione delle Prestazioni

Il caching è essenziale per migliorare le prestazioni di un API Gateway Frontend. Mettendo in cache i dati ad accesso frequente, è possibile ridurre il carico sui servizi di backend e migliorare i tempi di risposta per i client. Ecco alcune strategie di caching:

• Caching HTTP: Sfruttare i meccanismi di caching HTTP (ad es. header `Cache-Control`) per mettere in cache le risposte nel browser e nei proxy intermedi.
• Caching in Memoria: Utilizzare cache in memoria (ad es. Redis, Memcached) per mettere in cache i dati ad accesso frequente sul gateway.
• Caching CDN: Utilizzare Content Delivery Network (CDN) per mettere in cache asset statici e risposte API più vicino al client.
• Caching delle Query GraphQL: Mettere in cache i risultati delle query GraphQL in base alla loro stringa di query e alle variabili. Questo può essere particolarmente efficace per le query eseguite di frequente. Apollo Server offre un supporto integrato per il caching delle query.

Quando si implementa il caching, considerare le strategie di invalidazione della cache per garantire che i client ricevano dati aggiornati. Le strategie comuni includono:

• Scadenza basata sul tempo: Impostare un tempo di scadenza fisso per i dati in cache.
• Invalidazione basata su eventi: Invalidare la cache quando i dati cambiano nei servizi di backend. Questo può essere ottenuto utilizzando webhook o code di messaggi.

Monitoraggio e Osservabilità

Il monitoraggio e l'osservabilità sono fondamentali per garantire la salute e le prestazioni del vostro API Gateway Frontend. Implementare un monitoraggio completo per tracciare le metriche chiave come:

• Latenza delle richieste: Il tempo necessario per elaborare una richiesta.
• Tassi di errore: La percentuale di richieste che risultano in errori.
• Throughput: Il numero di richieste elaborate per unità di tempo.
• Utilizzo delle risorse: Utilizzo di CPU, memoria e rete del gateway e dei servizi di backend.

Utilizzare il tracing per tracciare le richieste mentre attraversano il sistema, identificando colli di bottiglia e problemi di prestazioni. Il logging fornisce informazioni preziose sul comportamento del gateway e dei servizi di backend.

Gli strumenti per il monitoraggio e l'osservabilità includono:

• Prometheus: Un sistema open-source di monitoraggio e alerting.
• Grafana: Uno strumento di visualizzazione dati e monitoraggio.
• Jaeger: Un sistema open-source di distributed tracing.
• Datadog: Una piattaforma di monitoraggio e sicurezza per applicazioni cloud.
• New Relic: Una piattaforma di digital intelligence per monitorare e migliorare le prestazioni del software.

Implementando un robusto monitoraggio e osservabilità, è possibile identificare e risolvere proattivamente i problemi, garantendo l'affidabilità e le prestazioni del vostro API Gateway Frontend.

Conclusione

Un API Gateway Frontend costruito con la Federazione GraphQL o lo Schema Stitching può semplificare notevolmente l'accesso ai dati, migliorare le prestazioni e ottimizzare l'esperienza degli sviluppatori nelle applicazioni web moderne. La Federazione GraphQL fornisce una soluzione potente e scalabile per comporre API GraphQL distribuite, mentre lo Schema Stitching offre un approccio più flessibile per combinare schemi esistenti. Considerando attentamente i requisiti specifici della vostra applicazione e i compromessi tra queste tecniche, potete scegliere l'approccio migliore per costruire un API Gateway Frontend robusto ed efficiente.

Ricordatevi di implementare un'adeguata autenticazione e autorizzazione, strategie di caching, e monitoraggio e osservabilità per garantire la sicurezza, le prestazioni e l'affidabilità del vostro gateway. Abbracciando queste best practice, potrete sbloccare il pieno potenziale di GraphQL e costruire applicazioni web moderne che offrono esperienze utente eccezionali.